home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / libkmid / libkmid.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  6.7 KB  |  227 lines
  1. /*  libkmid.h     - class KMidSimpleAPI that makes it easy to use libkmid
  2.             and a C wrapper.
  3.     This file is part of LibKMid 0.9.5
  4.     Copyright (C) 2000  Antonio Larrosa Jimenez
  5.     LibKMid's homepage : http://www.arrakis.es/~rlarrosa/libkmid.html
  6.  
  7.     This library is free software; you can redistribute it and/or
  8.     modify it under the terms of the GNU Library General Public
  9.     License as published by the Free Software Foundation; either
  10.     version 2 of the License, or (at your option) any later version.
  11.  
  12.     This library is distributed in the hope that it will be useful,
  13.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  14.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15.     Library General Public License for more details.
  16.  
  17.     You should have received a copy of the GNU Library General Public License
  18.     along with this library; see the file COPYING.LIB.  If not, write to
  19.     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  20.     Boston, MA 02110-1301, USA.
  21.  
  22.     Send comments and bug fixes to Antonio Larrosa <larrosa@kde.org>
  23.  
  24. ***************************************************************************/
  25. #ifndef _LIBKMID_H
  26. #define _LIBKMID_H 
  27.  
  28. #ifdef __cplusplus
  29.  
  30. #include <kdelibs_export.h>
  31.  
  32. /**
  33.  * Simple API covering most of the uses of libkmid.
  34.  *
  35.  * You can use the members of this class in pure C applications, just by using
  36.  * the same name as the corresponding function member. 
  37.  * 
  38.  * Suppose you're developing a game and you want to play some background music
  39.  * while the user is playing. You only have to call :
  40.  * 
  41.  * @li kMidInit();
  42.  * @li kMidLoad("RideOfTheValkyries.mid");
  43.  * @li kMidPlay();
  44.  *
  45.  * When the user decides to quit the game, use 
  46.  *
  47.  * @li kMidStop();
  48.  * @li kMidDestruct();
  49.  *
  50.  * to stop the music and release the memory allocated by libkmid.
  51.  *
  52.  * @short A very simple API around the rest of libkmid.
  53.  * @version 0.9.5 17/01/2000
  54.  * @author Antonio Larrosa Jimenez <larrosa@kde.org> 
  55.  */
  56. class KMID_EXPORT KMidSimpleAPI 
  57. {
  58.   private:
  59.     class KMidSimpleAPIPrivate;
  60.     KMidSimpleAPIPrivate *d;
  61.  
  62.   public:
  63.  
  64.     /**
  65.      * Initializes libkmid. Creates the DeviceManager object, and initializes
  66.      * some variables that will be used later.
  67.      *
  68.      * @return 0 if OK, and a positive number when there's any error (for
  69.      * example, because the /dev/sequencer device couldn't be opened, be it
  70.      * because it was already opened by another application, or because the
  71.      * sound card wasn't configured)
  72.      */
  73.     static int kMidInit(void);
  74.  
  75.     /**
  76.      * Loads a song that will be played with the next call to kMidPlay().
  77.      */
  78.     static int kMidLoad(const char *filename);
  79.  
  80.     /**
  81.      * Plays the song currently loaded with kMidLoad().
  82.      * kMidPlay forks in order to play the song in a different process, it
  83.      * exits inmediately, so that the application can follow the normal
  84.      * execution flow while the sone is played.
  85.      *
  86.      * If loop is 0 the song is played once and then the child process
  87.      * finishes. If loop is 1, the song is played repeatedly until
  88.      * kMidStop() is called. You can call kMidStop() anytime you want
  89.      * (also if loop is 0) to stop the song and kill the child process.
  90.      *
  91.      * @see kMidStop
  92.      * @see kMidIsPlaying
  93.      */
  94.     static int kMidPlay(int loop=0);
  95.  
  96.     /**
  97.      * Stops playing a song inmediatly. It doesn't return until the child
  98.      * process that is playing the song is terminated.
  99.      *
  100.      * @see kMidPlay
  101.      */
  102.     static int kMidStop(void);
  103.  
  104.     /**
  105.      * Releases the memory allocated by libkmid. To continue playing, you must
  106.      * first make a(nother) call to kMidInit().
  107.      */
  108.     static void kMidDestruct(void);
  109.  
  110.     /**
  111.      * Returns 1 if the library is playing a song, and 0 if it's not.
  112.      * @see kMidPlay
  113.      */
  114.     static int kMidIsPlaying(void);
  115.  
  116.     /**
  117.      * Returns the number of MIDI devices  ( MIDI ports + synthesizers )
  118.      * @see DeviceManager::midiPorts
  119.      * @see DeviceManager::synthDevices
  120.      * @see kMidName
  121.      * @see kMidType
  122.      */
  123.     static int kMidDevices(void);
  124.  
  125.     /**
  126.      * Returns the name of the i-th device . In case libkmid wasn't yet
  127.      * initialized ( see kMidInit() ), the return value is NULL, and in
  128.      * case the parameter has a value out of the valid range 
  129.      * ( see kMidDevices() ) it returns an empty string.
  130.      *
  131.      * @see kMidDevices
  132.      * @see kMidType
  133.      */
  134.     static const char *kMidName(int i);
  135.  
  136.     /**
  137.      * Returns the type of the i-th device . In case libkmid wasn't yet
  138.      * initialized ( see kMidInit() ), the return value is NULL, and in
  139.      * case the parameter has a value out of the valid range 
  140.      * ( see kMidDevices() ) it returns an empty string.
  141.      *
  142.      * @see kMidDevices
  143.      * @see kMidName
  144.      */
  145.     static const char *kMidType(int i);
  146.  
  147.     /**
  148.      * Sets the MIDI device to use when playing a song.
  149.      * @see kMidDevices
  150.      * @see kMidName
  151.      * @see DeviceManager
  152.      */
  153.     static void kMidSetDevice(int i);
  154.  
  155.     /**
  156.      * Sets the Midi Mapper to use. Most of the users won't need a midi mapper,
  157.      * but there're still non-General Midi synthesizers out there, and people
  158.      * with one of those will get much better sound quality by using a MIDI
  159.      * mapper. 
  160.      *
  161.      * Please have a look at KMid's documentation for more information
  162.      * about MIDI mappers and how to write a MIDI mapper for your keyboard.
  163.      */
  164.     static void kMidSetMidiMapper(const char *mapfilename);
  165.  
  166.     /**
  167.      * Returns the version number of libkmid, i.e. "0.9.5" or "1.0 Beta"
  168.      */
  169.     static const char *kMidVersion(void);
  170.  
  171.     /**
  172.      * Returns the copyright notice that applications using libkmid should print
  173.      * to the user in an about box or somewhere visible.
  174.      * I.e. 
  175.      *
  176.      * "LibKMid 0.9.5 (C) 1997-2000 Antonio Larrosa Jimenez <larrosa@kde.org>. Spain"
  177.      */ 
  178.     static const char *kMidCopyright(void);
  179.  
  180. };
  181.  
  182.  
  183.  
  184. extern "C" {
  185.  
  186. #else
  187. #define KMID_EXPORT
  188. #endif
  189.  
  190.  
  191. KMID_EXPORT  int    kMidInit(void);
  192. KMID_EXPORT  int    kMidLoad(const char *filename);
  193. KMID_EXPORT  int    kMidPlay(void);
  194. KMID_EXPORT  int    kMidStop(void);
  195. KMID_EXPORT  void   kMidDestruct(void);
  196. KMID_EXPORT  int    kMidIsPlaying(void);
  197. KMID_EXPORT  int    kMidDevices(void);
  198. KMID_EXPORT  const char * kMidName(int i);
  199. KMID_EXPORT  const char * kMidType(int i);
  200. KMID_EXPORT  void   kMidSetDevice(int i);
  201. KMID_EXPORT  void   kMidSetMidiMapper(const char *mapfilename);
  202. KMID_EXPORT  const char * kMidVersion(void);
  203. KMID_EXPORT  const char * kMidCopyright(void);
  204.  
  205.  
  206.  
  207. #ifdef __cplusplus
  208.  
  209. }
  210.  
  211. /**
  212.  * @internal
  213.  */
  214. extern struct kMidData 
  215. {
  216.   class DeviceManager *midi;
  217.   class MidiPlayer *player;
  218.   class MidiMapper *map;
  219.   struct PlayerController *pctl;
  220.   int pctlsmID;
  221.   int pid;
  222. } kMid;
  223. #endif
  224.  
  225.  
  226. #endif
  227.